{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "view-in-github",
        "colab_type": "text"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/bitkira/Colab/blob/main/tutorial_notebooks_zh/quickstart.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "400b083a",
      "metadata": {
        "id": "400b083a"
      },
      "source": [
        "# EvoAgentX 快速开始指南\n",
        "\n",
        "本快速开始指南将引导你完成使用 EvoAgentX 的基础步骤。在本教程中，你将学习如何：\n",
        "1. 配置用于访问 LLM 的 API 密钥  \n",
        "2. 自动创建并执行工作流  \n",
        "\n",
        "## 安装"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "44ee039e",
      "metadata": {
        "id": "44ee039e"
      },
      "outputs": [],
      "source": [
        "!pip install git+https://github.com/EvoAgentX/EvoAgentX.git"
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "!pip install PyPDF2 selenium html2text fastmcp"
      ],
      "metadata": {
        "id": "28CC3L--aroa"
      },
      "id": "28CC3L--aroa",
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "id": "5eab7525",
      "metadata": {
        "id": "5eab7525"
      },
      "source": [
        "请参阅 [安装指南](./installation.md) 获取更多详细信息。\n",
        "\n",
        "## API 密钥 和 LLM 设置\n",
        "\n",
        "要在 EvoAgentX 中执行工作流，首先需要配置用于访问大模型（LLM）的 API 密钥。推荐以下两种方式：\n",
        "\n",
        "### 方法一：在终端设置环境变量\n",
        "\n",
        "此方法直接在系统环境中设置 API 密钥。\n",
        "\n",
        "对于 Linux/macOS："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "6903a765",
      "metadata": {
        "id": "6903a765"
      },
      "outputs": [],
      "source": [
        "export OPENAI_API_KEY=<你的-openai-api-key>"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "f7f37d86",
      "metadata": {
        "id": "f7f37d86"
      },
      "source": [
        "\n",
        "对于 Windows 命令提示符："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "aa02d2b2",
      "metadata": {
        "id": "aa02d2b2"
      },
      "outputs": [],
      "source": [
        "set OPENAI_API_KEY=<你的-openai-api-key>"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "90466632",
      "metadata": {
        "id": "90466632"
      },
      "source": [
        "\n",
        "对于 Windows PowerShell："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "6c83ffa6",
      "metadata": {
        "id": "6c83ffa6"
      },
      "outputs": [],
      "source": [
        "$env:OPENAI_API_KEY=\"<你的-openai-api-key>\"  # 引号是必需的"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "7fa4e388",
      "metadata": {
        "id": "7fa4e388"
      },
      "source": [
        "\n",
        "设置完成后，可在 Python 中这样获取："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "85aea177",
      "metadata": {
        "id": "85aea177"
      },
      "outputs": [],
      "source": [
        "import os\n",
        "OPENAI_API_KEY = os.getenv(\"OPENAI_API_KEY\")"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "457efbdf",
      "metadata": {
        "id": "457efbdf"
      },
      "source": [
        "\n",
        "### 方法二：使用 `.env` 文件\n",
        "\n",
        "也可以在项目根目录下创建 `.env` 文件来存储 API 密钥。\n",
        "\n",
        "文件内容示例："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "3394011c",
      "metadata": {
        "id": "3394011c"
      },
      "outputs": [],
      "source": [
        "OPENAI_API_KEY=<你的-openai-api-key>"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "5549149c",
      "metadata": {
        "id": "5549149c"
      },
      "source": [
        "\n",
        "然后在 Python 中使用 `python-dotenv` 加载："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "2840c676",
      "metadata": {
        "id": "2840c676"
      },
      "outputs": [],
      "source": [
        "from dotenv import load_dotenv\n",
        "import os\n",
        "\n",
        "load_dotenv()  # 从 .env 文件加载环境变量\n",
        "OPENAI_API_KEY = os.getenv(\"OPENAI_API_KEY\")"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "0f6e9149",
      "metadata": {
        "id": "0f6e9149"
      },
      "source": [
        "\n",
        "🔐 提示：切勿将 `.env` 文件提交到公共平台（如 GitHub），请将其添加到 `.gitignore`。\n",
        "\n",
        "### 在 EvoAgentX 中配置并使用 LLM\n",
        "\n",
        "配置好 API 密钥后，可按如下方式初始化并使用 LLM："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "d636baf6",
      "metadata": {
        "id": "d636baf6"
      },
      "outputs": [],
      "source": [
        "from evoagentx.models import OpenAILLMConfig, OpenAILLM\n",
        "import os\n",
        "\n",
        "# 从环境加载 API 密钥\n",
        "OPENAI_API_KEY = os.getenv(\"OPENAI_API_KEY\")\n",
        "\n",
        "# 定义 LLM 配置\n",
        "openai_config = OpenAILLMConfig(\n",
        "    model=\"gpt-4o-mini\",       # 指定模型名称\n",
        "    openai_key=OPENAI_API_KEY, # 直接传入密钥\n",
        "    stream=True,               # 启用流式响应\n",
        "    output_response=True       # 打印响应到标准输出\n",
        ")\n",
        "\n",
        "# 初始化语言模型\n",
        "llm = OpenAILLM(config=openai_config)\n",
        "\n",
        "# 从 LLM 生成响应\n",
        "response = llm.generate(prompt=\"What is Agentic Workflow?\")"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### 方式三：配置colab\n",
        "下面的代码可以从colab中读取apikey"
      ],
      "metadata": {
        "id": "V5Oc1BoQBIkm"
      },
      "id": "V5Oc1BoQBIkm"
    },
    {
      "cell_type": "code",
      "source": [
        "import os\n",
        "from dotenv import load_dotenv\n",
        "from evoagentx.models import OpenAILLMConfig, OpenAILLM\n",
        "from evoagentx.agents import CustomizeAgent\n",
        "\n",
        "try:\n",
        "    from google.colab import userdata\n",
        "    OPENAI_API_KEY = userdata.get(\"OPENAI_API_KEY\")\n",
        "except ImportError:\n",
        "    OPENAI_API_KEY = None\n",
        "\n",
        "if not OPENAI_API_KEY:\n",
        "    load_dotenv()\n",
        "    OPENAI_API_KEY = os.getenv(\"OPENAI_API_KEY\")\n",
        "\n",
        "# Configure LLM\n",
        "openai_config = OpenAILLMConfig(\n",
        "    model=\"gpt-4o-mini\",\n",
        "    openai_key=OPENAI_API_KEY,\n",
        "    stream=True\n",
        ")\n",
        "\n",
        "llm = OpenAILLM(config=openai_config)"
      ],
      "metadata": {
        "id": "1fiEKkQ4BT1L"
      },
      "id": "1fiEKkQ4BT1L",
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "id": "a1cbc4f6",
      "metadata": {
        "id": "a1cbc4f6"
      },
      "source": [
        "\n",
        "你可以在 [LLM 模块指南](./modules/llm.md) 中找到更多关于支持的 LLM 类型及其参数的详细信息。\n",
        "\n",
        "## 自动工作流生成与执行\n",
        "\n",
        "配置完成后，即可在 EvoAgentX 中自动生成并执行智能工作流。本节展示生成工作流、实例化代理并运行的核心步骤。\n",
        "\n",
        "首先，导入必要的模块：\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "bc582426",
      "metadata": {
        "id": "bc582426"
      },
      "outputs": [],
      "source": [
        "from evoagentx.workflow import WorkFlowGenerator, WorkFlowGraph, WorkFlow\n",
        "from evoagentx.agents import AgentManager"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "4368f51d",
      "metadata": {
        "id": "4368f51d"
      },
      "source": [
        "\n",
        "### 第一步：生成工作流与任务图\n",
        "使用 `WorkFlowGenerator` 基于自然语言目标自动创建工作流："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "cc170f01",
      "metadata": {
        "id": "cc170f01"
      },
      "outputs": [],
      "source": [
        "goal = \"Generate html code for the Tetris game that can be played in the browser.\"\n",
        "wf_generator = WorkFlowGenerator(llm=llm)\n",
        "workflow_graph: WorkFlowGraph = wf_generator.generate_workflow(goal=goal)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "3c8aba3a",
      "metadata": {
        "id": "3c8aba3a"
      },
      "source": [
        "`WorkFlowGraph` 是一个数据结构，用于存储整体工作流计划，包括任务节点及其关系，但尚未包含可执行的代理。\n",
        "\n",
        "可选：可视化或保存生成的工作流："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "a6a260d3",
      "metadata": {
        "id": "a6a260d3"
      },
      "outputs": [],
      "source": [
        "# 可视化工作流结构（可选）\n",
        "workflow_graph.display()\n",
        "\n",
        "# 将工作流保存为 JSON 文件（可选）\n",
        "workflow_graph.save_module(\"/path/to/save/workflow_demo.json\")"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "6c21991e",
      "metadata": {
        "id": "6c21991e"
      },
      "source": [
        "我们提供了一个生成的工作流示例 [here](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/output/tetris_game/workflow_demo_4o_mini.json)。你可以重新加载保存的工作流："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "a5115820",
      "metadata": {
        "id": "a5115820"
      },
      "outputs": [],
      "source": [
        "workflow_graph = WorkFlowGraph.from_file(\"/path/to/save/workflow_demo.json\")"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "9570d769",
      "metadata": {
        "id": "9570d769"
      },
      "source": [
        "\n",
        "### 第二步：创建并管理执行代理\n",
        "\n",
        "使用 `AgentManager` 基于工作流图实例化并管理代理："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "eced435c",
      "metadata": {
        "id": "eced435c"
      },
      "outputs": [],
      "source": [
        "agent_manager = AgentManager()\n",
        "agent_manager.add_agents_from_workflow(workflow_graph, llm_config=openai_config)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "4df66a22",
      "metadata": {
        "id": "4df66a22"
      },
      "source": [
        "\n",
        "### 第三步：执行工作流\n",
        "代理准备就绪后，可以创建 `WorkFlow` 实例并运行："
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "f4b4de79",
      "metadata": {
        "id": "f4b4de79"
      },
      "outputs": [],
      "source": [
        "workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)\n",
        "output = workflow.execute()\n",
        "print(output)"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "如果上面代码报错，请执行下面的代码"
      ],
      "metadata": {
        "id": "WZXvATCdnLlX"
      },
      "id": "WZXvATCdnLlX"
    },
    {
      "cell_type": "code",
      "source": [
        "import nest_asyncio\n",
        "\n",
        "nest_asyncio.apply()\n",
        "workflow = WorkFlow(graph=workflow_graph, agent_manager=agent_manager, llm=llm)\n",
        "output = workflow.execute()\n",
        "print(output)"
      ],
      "metadata": {
        "id": "xIB1AIbbm5Dt"
      },
      "id": "xIB1AIbbm5Dt",
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "id": "6518c104",
      "metadata": {
        "id": "6518c104"
      },
      "source": [
        "\n",
        "更多示例请参见 [完整工作流演示](https://github.com/EvoAgentX/EvoAgentX/blob/main/examples/workflow_demo.py)。"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "provenance": [],
      "include_colab_link": true
    },
    "language_info": {
      "name": "python"
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}